Agent skills: restructure into Agents/skills and develop authoring guidance - #72
Open
tlmquintino wants to merge 4 commits into
Open
Agent skills: restructure into Agents/skills and develop authoring guidance#72tlmquintino wants to merge 4 commits into
tlmquintino wants to merge 4 commits into
Conversation
Introduces a top-level `Agents/` area with `skills/` beneath it, so that future agent artefacts (subagents, prompts, evaluation material) have an obvious home alongside skills rather than accumulating in a single skills-only directory. - git mv "Agent Skills" -> Agents/skills (rename detected; no content change) - update all inbound links: root README, Guidelines/Ai-Contributions-To-Software, Legal/Open-Sourcing-Software, ADR-009 - fix outbound relative links inside the moved files, which are now one level deeper (../ -> ../../ in the skills README; ../../ -> ../../../ in both SKILL.md files) Link check: 0 broken. The remaining bare `](LICENSE)` references are inside template blocks showing what a target repository's README should contain, not links within the Codex.
The previous README predated a cross-vendor standard and stated that none existed. The Agent Skills specification (https://agentskills.io/specification) now fills that gap, so this rewrites the README around it. Adds: - what a skill is, and the progressive-disclosure model agents use - directory layout (SKILL.md, scripts/, references/, assets/) - the full frontmatter table with the specification's constraints, including the name regex and the rule that name must match the directory - guidance on writing the body: explicit decision rules, stop conditions, and restating the trigger outside the frontmatter - size budgets per load stage, and the 500-line SKILL.md ceiling - validation via skills-ref - ECMWF house rules layered on the specification: report-and-gate, model-agnostic, never invent or hide findings, redact secrets, British English, project-agnostic - installation paths per harness, preferring the vendor-neutral .agents/skills/ location, plus a table of per-product setup documentation from https://agentskills.io/clients - a checklist for contributing a new skill
Ports five workflows into project- and language-agnostic skills written to the Agent Skills specification. Each discovers the repository's own build, test and documentation layout rather than hard-coding paths, tools or organisation names. - review-pull-request — works through review feedback until it converges. Merges two prior workflows (respond-to-review and the Copilot review loop), since the mechanics are identical and only the reviewer differs. Records the hard-won bot mechanics: the literal `[bot]` reviewer suffix is the only request form that works, and the `requested_reviewers` list cycling back to empty is the terminating signal. Notes that `gh pr view` does not show inline comments, so the GraphQL reviewThreads query is required. Never merges. - doc-fact-check — executes runnable doc examples and verifies falsifiable claims against source. Keeps the distinction between a documentation bug and an environment problem, and refuses to invent imports to make a block run. Proposes fixes without applying them. - onboard-repository — read-only survey producing a structured mental model. Trusts code over documents and reports the drift between them. - robustness-audit — merges error-handling and edge-case auditing, which belong together: an unhandled edge case usually surfaces as a bad error. Severity ladder led by silent-wrong-answer. Asks before changing ambiguous or public behaviour. - improve-code-coverage — treats coverage as a proxy rather than a goal. Categorises each gap (testable / defensive / dead / environment-specific), prioritises by risk over line count, and deletes dead code rather than suppressing it. Also splits the README index into governance skills (which gate and never act) and development skills (which may change code, but still never merge, publish or release, and ask before changing public behaviour). All five validate against the specification: name matches directory, name regex and length, description present and within 1024 characters, no unknown frontmatter keys, and each SKILL.md under the 500-line ceiling.
Found by running the skill against this very pull request: Copilot replied with 'unable to review ... reached their quota limit'. That is posted as a review, so the review count rises while no finding is produced. An agent following the previous wording would treat the rising count as findings and loop forever: every retry posts another error review, so the count keeps rising and the no-new-review stop condition is never reached. Adds a third polling outcome for a service-error review, with the rule to read the review body before treating a rising count as findings, a cap of one retry, and an explicit instruction to report that the pull request has NOT been reviewed — so an unreviewed pull request is never mistaken for a clean one.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
Groundwork for further development of the Codex agent skills.
This PR is being developed incrementally. It starts with the directory
restructure and will go on to expand the skills README into proper authoring
guidance, and to add further reusable skills.
Done so far
1.
Agent Skills/→Agents/skills/Introduces a top-level
Agents/area withskills/beneath it, so future agentartefacts (subagents, prompts, evaluation material) have an obvious home rather
than accumulating in a skills-only directory.
git mv(rename detected — no content change to the skills themselves)README.md,Guidelines/Ai-Contributions-To-Software.md,Legal/Open-Sourcing-Software.md,ADR/ADR-009-Repository-Audit-Store.md(
../→../../in the skills README;../../→../../../in bothSKILL.mds)Planned in this PR
Agents/skills/README.mdas authoring guidance: how to write skillsto the Agent Skills specification
(frontmatter fields and constraints, progressive disclosure,
scripts/,references/,assets/, size budgets, validation), plus installationinstructions per harness based on the
client list.
The current README predates the specification and still says "there is no
cross-vendor standard for agent skills yet" — that is now out of date.
Candidates are being evaluated and will be proposed before they are written.
Notes for review
Reviewing commit-by-commit is easiest — the rename is isolated in its own commit.